home *** CD-ROM | disk | FTP | other *** search
/ EuroCD 3 / EuroCD 3.iso / Programming / BlitzBasic / TRITONBLITZ / BlitzLibs / Libdocs+demos / DBaseLib / dbaselib_1_06.doc < prev   
Encoding:
Text File  |  1998-06-24  |  19.1 KB  |  539 lines
  1. Database Function Library
  2. Graham .A. Kennedy (gakennedy@cix.compulink.co.uk)
  3. Version: 1.0  (20/02/95)
  4. Library Number : 10 (needs real number defining)
  5.  
  6.  
  7. ------------------- Database Library Documentation ---------------------
  8.  
  9. Introduction:
  10.   This library is provided to supply Blitz Basic with a number of simple
  11. Database functions, which may be used either, obviously within a database
  12. application (eg. the enclosed Address book program) or any program which
  13. needs an array which can expand upto the size of the free memory available.
  14. It also includes a number of functions which may be of use to anyone
  15. wishing to use fixed length strings within a newtype.
  16.  
  17. Concepts:
  18.   Some of the features of the database probably need some additional
  19. description before we launch straight into the command syntax, so here
  20. we go... hope it's not too boring...
  21.  
  22. Database structure -
  23.   The database is controlled by a Blitz Object, which can be accessed
  24. from the compiler options requester. Initially the number of databases
  25. is set to 16, but this can be increased (or decreased) depending on your
  26. requirements.
  27.  
  28.   The database itself is stored as a standard Amiga Exec name list, and
  29. uses the internal internal functions to create, add and remove entries.
  30.  
  31. A database may be 'KEYED' ie. all or part of the record could be used as
  32. a key. If you add data to a keyed file it will be inserted in key order.
  33. Therefore, a keyed database is automatically in ascending order, and
  34. requires no sorting.
  35.  
  36. Fixed length strings -
  37.  These are a bit of a cludge to get around the fact that Blitz only stores
  38. a pointer to a string inside a newtype variable. Storing a string within
  39. the newtype itself, allows allsorts of interesting tricks, such as passing
  40. a database to a GTListview gadget to display, or saving a whole newtype to
  41. disk with one command. They are implemented by using a byte array within
  42. the newtype. eg.
  43.  
  44.   NewType.mytype
  45.     name.b[30]:;  Fixed length string 30 characters in length
  46.     addrs.b[60]:;    "      "     "    60     "       "    "
  47.     age.l
  48.   end newtype
  49.  
  50.   deftype.mytype test:; make test a variable of mytype.
  51.  
  52. I will use this example when trying to describe the function of some
  53. of the following commands.
  54.  
  55. ***** N O T E *****
  56. Please not you CANNOT use standard strings within a database Newtype.
  57.  
  58. Known Bugs:
  59.   As far as I can tell there is only one known bug, which I hope will not
  60.   be too much of a problem.
  61.   If a database is filled so that it automatically expands, the total size
  62.   of the new database is then used whenever the database is reloaded from
  63.   disk, therefore taking up more memory than actually required.
  64.   eg. a database is created with 500 records, and expands by 100 records
  65.   each time it fills up. If 700 records are added then 600 deleted (leaving
  66.   100 records in the database). Whenever this database is saved to disk and
  67.   reloaded it will allocate space for 700 records when reloading, even though
  68.   only 100 records are loaded).
  69.  
  70.   So far I havn't found too many problems with this situation, I do know how
  71.   to fix this, and probably will if anyone thinks the library is worthwhile.
  72.  
  73. ------------------------------ Command Documentation ---------------------
  74.  
  75.  
  76. Database Commands:
  77.  
  78. Statement     : StrToFls
  79.  
  80. Syntax        : StrToFls string$,flspointer,length[,padchar]
  81.  
  82. Description   : This allows you to set a fixed length string to a value
  83.                 contained in a string. If the string is shorter than the
  84.                 length requested the fixed length string will be padded
  85.                 using the character defined by 'padchar'. If 'padchar' is
  86.                 ommitted '0' is used. If the string is longer than 'length',
  87.                 only 'length' bytes will be copied.
  88.  
  89. Example       : ; copies "Joe Bloggs" to field \name in test variable and
  90.                 ; pads field with spaces.
  91.                 a$="Joe Bloggs"
  92.                 StrToFls a$,test\name,30,32
  93.  
  94.                             -----------------
  95.  
  96. Function      : FlsToStr
  97.  
  98. Syntax        : ret$=FlsToStr$(flspointer,length)
  99.  
  100. Description   : This allows you to convert a Fixed length string to a
  101.                 standard Blitz string. The string created is returned in
  102.                 ret$. The string will be copied either until the first '0'
  103.                 byte is found or 'length' bytes have been copied.
  104.  
  105. Example       : ; Copies "Joe Bloggs" back to a$
  106.                 a$=FlsToStr$(test\name,30)
  107.  
  108.                             -----------------
  109.  
  110. Function      : DBinit
  111.  
  112. Syntax        : ret.b=DBinit(db#,primary,secondary,recvar[,keylen[,offset]])
  113.  
  114. Description   : This command initialises and builds a database, if the
  115.                 database is already in use it will be destroyed and a
  116.                 new one created. If the database is created the function
  117.                 will return 1, if it fails it will return 0.
  118.                 db#       = Database number
  119.                 primary   = Number of record initially allocated to database
  120.                 secondary = Number of record to add if database fills up
  121.                 recvar    = variable to use to define record structure
  122.                 keylen    = key database on this number of bytes
  123.                 offset    = Offset the key this number of bytes from the
  124.                             start of the record.
  125.  
  126. Example       : ; define database number 1, give it space for 100 records
  127.                 ; initially, and expand the database by 10 records each time
  128.                 ; it fills up. Use our example newtype to define its structure
  129.                 ; and key it on the name field.
  130.                   ret=DBinit{1,100,10,test,30)
  131.                   if ret=1 then Nprint "Yippee, database defined"
  132.  
  133.                             -----------------
  134.  
  135. Function        : DBlistaddr
  136.  
  137. Syntax          : ret.l=DBlistaddr(db#)
  138.  
  139. Description     : This returns the address of the head of the Nodelist
  140.                   which can then be passed to functions which require a
  141.                   standard Amiga namelist as a parameter.
  142.  
  143. Example         : ; display our list of names in a GTlistview Gadget
  144.                   ; nb. to use this example my GTLIB mod is required.
  145.                   GTChangeListM 1,2,DBlistaddr(1)
  146.  
  147.                             -----------------
  148.  
  149. Command         : DBfirst
  150.  
  151. Syntax          : ret.b = DBfirst(DB#)
  152.                           DBfirst DB#
  153.  
  154. Description     : This command sets the current record pointer to the
  155.                   first record in the database, if the database is empty
  156.                   or undefined the function will return 0, otherwise it
  157.                   will return 1.
  158.  
  159. Example         : ; Set pointer to first record in our database
  160.                   ok=DBfirst(1)
  161.  
  162.                             -----------------
  163.  
  164. Command         : DBlast
  165.  
  166. Syntax          : ret.b = DBlast(DB#)
  167.                           DBlast DB#
  168.  
  169. Description     : This command sets the current record pointer to the
  170.                   last record in the database, if the database is empty
  171.                   or undefined the function will return 0, otherwise it
  172.                   will return 1.
  173.  
  174. Example         : ; Set pointer to last record in our database
  175.                   ok=DBlast(1)
  176.  
  177.                             -----------------
  178.  
  179. Command         : DBnext
  180.  
  181. Syntax          : ret.b = DBnext(DB#)
  182.                           DBnext DB#
  183.  
  184. Description     : This command sets the current record pointer to the
  185.                   next record in the database, if the database is empty,
  186.                   undefined or there are no more records the function will
  187.                   return 0, otherwise it will return 1.
  188.  
  189. Example         : ; Scan our database records, start to finish
  190.                   ok=DBfirst(1)
  191.                   while (ok)
  192.                     ok=DBnext(1)
  193.                   wend
  194.  
  195.                             -----------------
  196.  
  197. Command         : DBprev
  198.  
  199. Syntax          : ret.b = DBprev(DB#)
  200.                           DBprev DB#
  201.  
  202. Description     : This command sets the current record pointer to the
  203.                   previous record in the database, if the database is empty,
  204.                   undefined or there are no more records the function will
  205.                   return 0, otherwise it will return 1.
  206.  
  207. Example         : ; Scan our database records, finish to start
  208.                   ok=DBlast(1)
  209.                   while (ok)
  210.                     ok=DBprev(1)
  211.                   wend
  212.  
  213.                             -----------------
  214. Command         : DBadd
  215.  
  216. Syntax          : ret.b = DBadd(DB#,recvar)
  217.                           DBadd DB#,recvar
  218.  
  219. Description     : This adds the values stored in the record variable to the
  220.                   database at the current position. If it cannot be added, the
  221.                   function will return 0. If it adds OK, 1 will be returned.
  222.                   (In addition, if the add had to expand the size of the
  223.                   database, this function will return a 2, this is for
  224.                   information Only).
  225.                   If the database is keyed, the data is added at the
  226.                   correct position, to keep the database in order.
  227.  
  228. Example         : ; Add a record to our database
  229.                   StrToFls "Joe Bloggs",test\name,30
  230.                   StrToFls "Joes House",test\addrs,60
  231.                   test\age=32
  232.                   ok=DBadd(1,test)
  233.                   If ok then Nprint "Yippee, added a record"
  234.  
  235.                             -----------------
  236.  
  237.  
  238. Command         : DBaddLast
  239.  
  240. Syntax          : ret.b = DBaddLast(DB#,recvar)
  241.                           DBaddLast DB#,recvar
  242.  
  243. Description     : This adds the values stored in the record variable to
  244.                   the end of the database. If it cannot be added, the
  245.                   function will return 0. If it adds OK, 1 will be returned.
  246.                   (In addition, if the add had to expand the size of the
  247.                   database, this function will return a 2, this is for
  248.                   information Only).
  249.                   If the database is keyed, the data is added at the
  250.                   correct position rather than at the end.
  251.  
  252. Example         : ; Add a record to our database
  253.                   StrToFls "Joe Bloggs",test\name,30
  254.                   StrToFls "Joes House",test\addrs,60
  255.                   test\age=32
  256.                   ok=DBaddLast(1,test)
  257.                   If ok then Nprint "Yippee, added a record"
  258.  
  259.                             -----------------
  260.  
  261. Command         : DBaddFirst
  262.  
  263. Syntax          : ret.b = DBaddFirst(DB#,recvar)
  264.                           DBaddFirst DB#,recvar
  265.  
  266. Description     : This adds the values stored in the record variable to
  267.                   the start of the database. If it cannot be added, the
  268.                   function will return 0. If it adds OK, 1 will be returned.
  269.                   (In addition, if the add had to expand the size of the
  270.                   database, this function will return a 2, this is for
  271.                   information Only).
  272.                   If the database is keyed, the data is added at the
  273.                   correct position rather than at the start.
  274.  
  275. Example         : ; Add a record to our database
  276.                   StrToFls "Joe Bloggs",test\name,30
  277.                   StrToFls "Joes House",test\addrs,60
  278.                   test\age=32
  279.                   ok=DBaddFirst(1,test)
  280.                   If ok then Nprint "Yippee, added a record"
  281.  
  282.                             -----------------
  283.  
  284. Function        : DBrecs
  285.  
  286. Syntax          : ret.l=DBrecs(DB#)
  287.  
  288. Description     : Returns how many records are stored in the database.
  289.  
  290. Example         : Nprint "Database has ",DBrecs(1)," records in it"
  291.  
  292.                             -----------------
  293.  
  294. Command         : DBget
  295.  
  296. Syntax          : ret.b=DBget(DB#,recvar)
  297.                         DBget DB#,recvar
  298.  
  299. Description     : Retrieve the current record from the database
  300. into the
  301.                   record variable. If ok, the function returns 1, if the
  302.                   database is empty or undefined 0 is returned
  303.  
  304. Example         : ; lets get some data
  305.                   ok=DBfirst(1)
  306.                   if ok
  307.                     DBget 1,test
  308.                     Nprint "Name   :",FlsToStr$(test\name,30)
  309.                     Nprint "Address:",FlsToStr$(test\addrs,60)
  310.                     Nprint "Age    :",test\age
  311.                   end if
  312.  
  313.                             -----------------
  314.  
  315. Statement       : DBkill
  316.  
  317. Syntax          : DBkill DB#
  318.  
  319. Description     : Remove the current database from memory, if you do not
  320.                   remove a database it will be removed automatically when
  321.                   the program finishes.
  322.  
  323. Example         : ; I don't want ya no more, o database of mine
  324.                   DBkill 1
  325.  
  326.                             -----------------
  327.  
  328. Statement       : DBdelete
  329.  
  330. Syntax          : DBdelete DB#
  331.  
  332. Description     : Delete the current record from the database.
  333. NB. To
  334.                   keep the speed of the library at a maximum, deleted
  335.                   records are NOT reallocated. Therefore if you do a
  336.                   large number of deletes it may be worth reorganising
  337.                   the database. This can be performed by saving it off
  338.                   (eg. to ram:) and reloading it.
  339.  
  340. Example         : ; I hate that first record
  341.                   ok=DBfirst(1)
  342.                   if ok then DBdelete 1
  343.  
  344.                             -----------------
  345.  
  346. Command         : DBsetpos
  347.  
  348. Syntax          : ret.b=DBsetpos(DB#,record#)
  349.                         DBsetpos DB#,record#
  350.  
  351. Description     : Positions the record pointer at record#, if record#
  352.                   is greater than the number of records in the database
  353.                   it will make the last record current.
  354.  
  355. Example         : ; I wanna be, at record number 3
  356.                   DBsetpos 1,3
  357.  
  358.                             -----------------
  359.  
  360. Statement       : DBcasesense
  361.  
  362. Syntax          : DBcasesense ON|OFF
  363.  
  364. Description     : Switch case sensitivity on or off for database searches
  365.                   and adds to keyed databases.
  366.  
  367.                              -----------
  368.  
  369. Statement       : DBsetkey
  370.  
  371. Syntax          : DBsetkey ON|OFF
  372.  
  373. Description     : Switch keying on or off for database additions.
  374.                   NB. If you switch off case sensitivity then add a record
  375.                   to a keyed database the database may no longer be in order,
  376.                   as yet there is no sort command to reverse this situation.
  377.                   Additions to an unkeyed database are MUCH faster.
  378.  
  379.                              -----------
  380.  
  381. Function        : DBmemtype
  382.  
  383. Syntax          : DBmemtype memtyp
  384.  
  385. Description     : Set type of memory to be used when creating new databases.
  386.                   FASTRAM = 0
  387.                   CHIPMEM = 2
  388.                   CLRMEM  = 65536
  389.  
  390.                              -----------
  391. Function        : DBfind
  392.  
  393. Syntax          : ret.b=DBfind(DB#,search$[,length,offset[,startrec]])
  394.  
  395. Description     : Search database from the beginning for a string.
  396.                   if length and offset are not supplied, the whole
  397.                   record is searched. If a record is found, 1 is returned
  398.                   and the record is made current. 0 is returned if the
  399.                   search fails. If you only want to search part of the
  400.                   record, use the offset to indicate how many bytes from
  401.                   the start of the record you want to start, and set length
  402.                   to the number of bytes to search.
  403.                   If startrec is supplied the search will start from the
  404.                   indicated record.
  405.  
  406. Example         : ; Find joes house by searching address fields
  407.                   ok=DBfind(1,"Joe",60,30)
  408.                   if ok
  409.                     DBget 1,test
  410.                     NPrint "Yeehaaa, joes still here"
  411.                     Nprint "Name   :",FlsToStr$(test\name,30)
  412.                     Nprint "Address:",FlsToStr$(test\addrs,60)
  413.                     Nprint "Age    :",test\age
  414.                   end if
  415.  
  416.                              -----------
  417.  
  418. Function        : DBfindnext
  419.  
  420. Syntax          : ret.b=DBfindnext(DB#)
  421.  
  422. Description     : Search for the next occurance of search$ in the database.
  423.                   If a record is found, 1 is returned and the record is made
  424.                   current. 0 is returned if the search fails.
  425.  
  426. Example         : ; Find all joes houses
  427.                   ok=DBfind(1,"Joe",60,30)
  428.                   while (ok)
  429.                     DBget 1,test
  430.                     NPrint "Yeehaaa, joes still here"
  431.                     Nprint "Name   :",FlsToStr$(test\name,30)
  432.                     Nprint "Address:",FlsToStr$(test\addrs,60)
  433.                     Nprint "Age    :",test\age
  434.                     ok=DBfindnext(1)
  435.                   wend
  436.  
  437.                              -----------
  438.  
  439. Statement       : DBupdate
  440.  
  441. Syntax          : DBupdate DB#,recvar
  442.  
  443. Description     : Updates the current record with the data held in recvar.
  444.                   If the database is keyed, it will be reinserted at the
  445.                   correct position.
  446.  
  447. Example         : ; Let Jim have Joes House
  448.                   DBget 1,test
  449.                   StrToFls "Jimmy Jones",test\name,30
  450.                   DBupdate 1,test
  451.  
  452.                             -----------------
  453.  
  454. Command         : DBload
  455.  
  456. Syntax          : ret.b=DBload(DB#,filename$)
  457.                         DBload DB#,filename$
  458.  
  459. Description     : Load a database from disk. If the database is already
  460.                   in use it will be destroyed. If the load fails the
  461.                   function will return 0, if OK it will return 1.
  462.  
  463.                             -----------------
  464.  
  465. Command         : DBsave
  466.  
  467. Syntax          : ret.b=DBsave(DB#,filename$)
  468.                         DBsave DB#,filename$
  469.  
  470. Description     : Save a database to disk. The database is reorganized
  471.                   as it is saved, removing any deleted records. If the
  472.                   save is OK, 1 will be returned, if it fails 0 will be
  473.                   returned.
  474.  
  475.                             -----------------
  476.  
  477. Function        : DBisnext
  478.  
  479. Syntax          : ret.b=DBisnext(DB#)
  480.  
  481. Description     : Tells you if there is a next record in the database.
  482.                   See, the example program for possible uses.
  483.  
  484.                             -----------------
  485.  
  486. Function        : DBisprev
  487.  
  488. Syntax          : ret.b=DBisprev(DB#)
  489.  
  490. Description     : Tells you if there is a previous record in the database.
  491.                   See, the example program for possible uses.
  492.  
  493.                             -----------------
  494.  
  495. Function        : DBcurrent
  496.  
  497. Syntax          : ret.l=DBcurrent(DB#)
  498.  
  499. Description     : Returns the current record number (0=database empty or
  500.                   not defined)
  501.  
  502.                             -----------------
  503.  
  504. Function        : DBmodified
  505.  
  506. Syntax          : ret.l=DBmodified(DB#)
  507.  
  508. Description     : Returns TRUE if the database has been modified since
  509.                   it was loaded or created.
  510.  
  511.                             -----------------
  512.  
  513. Function        : DBactive
  514.  
  515. Syntax          : ret.b=DBactive(DB#)
  516.  
  517. Description     : Returns True if the database is active (ie. defined)
  518.                   returns false otherwise
  519.  
  520.                             -----------------
  521.  
  522. Statement       : DBpush
  523.  
  524. Syntax          : DBpush
  525.  
  526. Description     : stores the current database pointer position
  527.  
  528.                             -----------------
  529.  
  530. Statement       : DBpop
  531.  
  532. Syntax          : DBpop
  533.  
  534. Description     : sets database pointer to the last record stored by DBpush
  535.  
  536.  
  537. ----------------       End Of Library Documentation   -----------------
  538.  
  539.  
  540.  
  541.